feat(agent): add AgentRegistry for centralized agent management

Introduces AgentRegistry, a lightweight and optional utility for registering, discovering, and session-scoping agents. Supports mapping tool subsets to agents and integrates with agent state and event loop patterns.

Description

This PR adds a new AgentRegistry class to the SDK, mirroring the design of the existing ToolRegistry but for agents. The registry provides:

• Centralized registration and discovery of agents.
• Optional session-scoped management, allowing agents to be grouped and managed per session or event loop.
• The ability to map subsets of tools to specific agents, supporting specialization and isolation.
• Clean integration with agent state and event loop patterns, while remaining lightweight and fully optional for simple use cases.
• No changes to the default single-agent workflow; the registry is opt-in for advanced/multi-agent scenarios.

Related Issues

N/A

Documentation PR

N/A (to be created if/when feature is merged)

Type of Change

• New feature

Testing

How have you tested the change?

• Ran hatch fmt --formatter and hatch fmt --linter to ensure code style and linting compliance.

• Ran hatch test to verify all unit tests pass.

• (Optionally) Ran hatch run test-integ to verify integration tests.

• Verified that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli.

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.